5 Deploy RTutor Problem Set as a Package on Github

Ways to distribute a RTutor problem set

Once you have created and tested one or several RTutor problem sets, you want to distribute them to users. There are different ways for doing so.

  1. Just provide the users a zip file that contains the .rps, and for RMarkdown based problem sets the .rmd file, as well as needed data sets. Let users manually extract those files in their working directory. It can also be nice to put everything into a folder to which you add a RStudio project file, and then zip the folder.

  2. Create an R package that contains one or more problem sets (including supplementary data) and host it on Github or CRAN.

  3. Host the problem set directly in the web using shinyapps.io or another web server that runs shiny server.

This vignette describes the second option.

Creating an R package for your problem set

This process describes how to create an R package for your problem set. Currently the infrastructure is designed for Shiny-based problem sets, but it can also be extended to RMarkdown-based problem sets.

Step 1 Create package skeleton with rtutor.package.skel

The RTutor package has a function rtutor.package.skel that creates a package skeleton for a problem set package. You first need to call create.ps to create all problem set files from your solution files. Here is an example:

  # Working folder that contains your solution file
  setwd("D:/libraries/RTutor/examples")

  # First generate your problem set in the usual manner
  ps.name = "Example"; sol.file = paste0(ps.name,"_sol.Rmd")
  libs = c() # character vector of all packages you load in the problem set
  create.ps(sol.file=sol.file, ps.name=ps.name, user.name=NULL,libs=libs, stop.when.finished=FALSE)

  # This function creates a skeleton for your problem set package
  rtutor.package.skel(sol.file=sol.file, ps.name=ps.name,libs=libs,
    pkg.name="RTutorExample",   # Name of the problem set package
    pkg.parent.dir = "D:/libraries/RTutorExample", # Parent directory 
    author="Sebastian Kranz", # Your name
    github.user="skranz",     # Your github user name
    extra.code.file=NULL, # name of extra.code.file
    var.txt.file=NULL,    # name of var.txt.file
    overwrite=FALSE  # Do you want to override if package directory exists?
  )

The call to rtutor.package.skel creates a package folder with your package name below the specified pkg.parent.dir folder. In your example above, the created package folder would be

D:/libraries/RTutorExample/RTutorExample

(Note: I personally often find it convenient to put the package as a subfolder of a folder with the same name. This allows me to store in the parent directory, here D:/libraries/RTutorExample/, files that I locally use, e.g. for testing something out, but that shall not be part of the Github project.)

Choosing a Package Name

It would be good to have a package name of the Form “RTutorXXX”. To quickly identify RTutor problem set packages. Please don’t use any special characters, nor spaces in your package name. If your name consists of words, use the Camel case conventiton to separate them, e.g. “RTutorBankRuns”. Don’t choose a package name that is too long.

Step 2 Create an RStudio Package Project for the created folder.

Now create in RStudio a new package project for your folder using the menus:

File -> New Project … -> Existing Directory

Chose as project folder your package folder, e.g. in our example, we would choose the folder D:/libraries/RTutorExample/RTutorExample.

See also the description here:

https://support.rstudio.com/hc/en-us/articles/200486488-Developing-Packages-with-RStudio

Step 3 Add data sets and other files

If you want to distribute the data sets used in your problem set directly with your problem sets, copy those data sets into the following subfolder of your package folder:

/inst/ps/problemset_name/material/

Also take a look at the /inst/ps/problemset_name folder. It should contain at least the .rps, _sol.rmd file. If your problem set uses an extra.code.file or var.text.file, those files should also be there, to be able to rebuild the .rps file from the solution file.

If you want no open access to the sample solution

If you want to avoid that students can easily access the solution, you have to remove the _sol.rmd file from the /inst/ps/problemset_name folder. The drawback is that then the problem set cannot be changed or rebuild from source by other researchers. Also make sure that you set the argument rps.has.sol = FALSE in your call to create.ps, since otherwise a sample solution can be created from the .rps file.

Step 4 Update DESCRIPTION and README.MD and choose licence

Edit the file “DESCRIPTION” - generate or update the problem set description / title - check the DATE and possibly update it - check and correct your name and email in the AUTHOR and MAINTAINER fields - check whether you agree with the licences and possibly adapt them - Here is an overview of different types of Creative Commons licenses:

  [https://creativecommons.org/licenses/](https://creativecommons.org/licenses/)

Edit the file “README.MD” - Add a brief description (2-3 lines) of the problem set.

Step 5 Build the package with RStudio

Try to build the package with RStudio with the menu point

Build -> Clean and Rebuild
  • Afterwards check whether you can run the problem set as explained in the README.MD file

Step 6 Optionally add additional problem sets in your package

A package can contain more than one problem set. Currently rtutor.package.skel only generates a package structure for a single problem set. Adding more problem sets requires manual adaption of the package.

6.1 Adapt package_info.r

The R folder of your new package contains a file package_info.r that has a content similar as follows:

ps.pkg.info = function() {
  # Name of this package
  package = "RTutorExample"
  
  # Name of problem sets in the package
  ps = c("Example")
  
  list(package=package, ps = ps)
}

If you want to have several problem sets, you must adapt the line ps = c("Example"). Say we want to add a second problem set “Example2”. We then must write

  ps = c("Example","Example2")

6.2 Create folder under inst/ps and copy files

You manually have to create a folder for your new problem set under inst/ps. For example if we add a problem set Example2, you need to create the folders

./inst/ps/Example2
./inst/ps/Example2/material

In the first folder, you copy your .rps file (and if you like other .rmd files like your solution file). In the material subfolder you copy data sets that your problem set uses.

6.3 Adapt README.MD

You finally should adapt the file README.MD to make the user aware of the multiple problem sets. In particular the command run.ps needs to specify the name of the problem set if another than the first problem set shall be run, e.g.

run.ps(user.name="Jon Doe", ps.name="Example2", package="RTutorExample",
       load.sav=TRUE, sample.solution=FALSE)

Step 7: Updating problem sets

If you want to update the problem sets in your package, simple copy manually the new files into the problem set folder under /inst/ps. Then build your new package, test it and upload the changes to Github. There is no need to create the whole package with the package skeleton again.

Host your package on Github

  • It is easiest to distribute your package if you host it as an open source project on Github.

    • There are different ways to host your package on Github. I just describe the way I use on Windows.

    • An alternative way to use Github is described here: http://r-pkgs.had.co.nz/git.html

  • Create a user account on Github by signing up here: https://github.com/

    • You can pick a user name that is related to your true name (first name and / or family name), like my user name “skranz” or some anonymous user name. I guess that is a matter of taste. Personally, I find names that link to the true name more convenient, but you can observe both on github.

  • Install Github Desktop:

    https://desktop.github.com/

    Documentation can be found here:

    https://docs.github.com/en/desktop

  • To add your package folder as github repository open Github Desktop and your file explorer and drag’n’drop your package folder from the explorer on the left your Github Desktop window.

  • After you have created your github project or you have changed it, you can commit your changes and then synchronize your local changes with the Github version.

  • Check whether you can see your package on the github webpage, as a repository under your username.

  • Check whether your package can be installed and run from Github in the way described in the README.md file.

Hosting problem set in the web using shinyapps.io

See the separate vignette.